# ESP32-S3 固件架构

```{admonition} 本文引用的文件
:class: note

- `CMakeLists.txt`
- `esp32_common.cmake`
- `main/CMakeLists.txt`
- `main/idf_component.yml`
- `boards/mpython_v3/mpconfigboard.cmake`
- `boards/labplus_Ledong_v2/mpconfigboard.cmake`
- `components/esp_lcd_jd9853/CMakeLists.txt`
- `components/gen_bmgr_codes/CMakeLists.txt`
- `makeimg.py`
```

## 产品概述
本仓库为 ESP32-S3 产品线（掌控板3.0、乐动掌控2.0等）的 MicroPython 固件工程，基于 ESP-IDF v5.x 与 CMake 构建系统组织代码。工程通过“顶层 CMake + 板级配置 + 组件化”的方式，将 MicroPython 核心、ESP-IDF 组件、用户自定义组件（LVGL/ESP-Who 等）与板型专属资源进行解耦，支持多板型一键构建与打包。目标用户为教育硬件开发者、系统集成商与创客工程师，适用于语音交互、AI视觉、GUI 显示、传感器采集与物联网通信等场景。

## 核心业务流程
- 选择板型：通过 MICROPY_BOARD 指定 mpython_v3 / labplus_Ledong_v2 等，顶层 CMake 加载对应 mpconfigboard.cmake，并合并 SDKCONFIG_DEFAULTS。
- 集成 IDF：包含 main/CMakeLists.txt 后引入 esp32_common.cmake，注册 MicroPython 主组件，链接 ESP-IDF 组件与 TinyUSB、音频/视频/AI 相关依赖。
- 生成引脚头：根据 pins.csv 与 make-pins.py 生成 pins.c/pins.h，供运行时 Pin/TouchPad 等模块使用。
- 冻结 Python 包：按板型 manifest.py 冻结第三方库与业务脚本到 ROM。
- 构建产物：idf.py build 产出 bootloader/partition/app；随后 merge_bin 调用 makeimg.py 将 VFS/LittleFS、语音模型、字体、TTS 数据等按分区表写入最终 bin，并在 S3 上生成 UF2。

```text
flowchart TD
A["设置 MICROPY_BOARD"] --> B["加载 boards/<board>/mpconfigboard.cmake"]
B --> C["合并 SDKCONFIG_DEFAULTS"]
C --> D["include main/CMakeLists.txt -> esp32_common.cmake"]
D --> E["注册 MicroPython 主组件与 IDF 依赖"]
E --> F["生成 pins.c/pins.h"]
F --> G["编译应用与组件"]
G --> H["merge_bin: makeimg.py 打包固件"]
H --> I{"IDF_TARGET=ESP32S2/S3?"}
I --> |是| J["生成 .uf2"]
I --> |否| K["仅输出 .bin"]
```

图表来源
- `CMakeLists.txt:12-46`
- `esp32_common.cmake:243-265`
- `esp32_common.cmake:355-378`
- `makeimg.py:106-222`

章节来源
- `CMakeLists.txt:12-46`
- `esp32_common.cmake:243-265`
- `esp32_common.cmake:355-378`
- `makeimg.py:106-222`

## 功能模块清单
- 构建系统与入口
  - 顶层 CMake：定义板型、合并 sdkconfig、包含 IDF 项目、注册 merge_bin 目标、锁定文件检查。
  - main/CMakeLists.txt：设置端口路径并引入 esp32_common.cmake。
  - esp32_common.cmake：聚合 MicroPython 源、扩展模块、端口适配、TinyUSB、IDF 组件、编译选项与链接片段。
- 板型配置体系
  - mpython_v3：启用 SPIRAM、BLE、240MHz、板级 builtin 源与 frozen manifest。
  - labplus_Ledong_v2：在 mpython_v3 基础上追加 ESP-Who 相关组件目录以启用 AI 视觉能力。
- 自定义组件（components）
  - esp_lcd_jd9853：屏幕驱动组件，依赖 esp_lcd，私有依赖 driver。
  - gen_bmgr_codes：基于 esp_board_manager 生成板信息代码，整包归档。
- 依赖管理（idf_component.yml）
  - 声明 mdns/tinyusb/esp-sr/esp_audio_codec/esp_video/esp32-camera 等官方组件，以及本地 gmf_* 系列组件路径覆盖。
- 固件打包（makeimg.py）
  - 读取分区表，组装 bootloader/partitions/application/VFS/voice_data/model，必要时生成 UF2。

章节来源
- `CMakeLists.txt:12-46`
- `CMakeLists.txt:79-106`
- `main/CMakeLists.txt:1-14`
- `esp32_common.cmake:40-55`
- `esp32_common.cmake:182-224`
- `esp32_common.cmake:277-329`
- `boards/mpython_v3/mpconfigboard.cmake:1-44`
- `boards/labplus_Ledong_v2/mpconfigboard.cmake:1-50`
- `components/esp_lcd_jd9853/CMakeLists.txt:1-8`
- `components/gen_bmgr_codes/CMakeLists.txt:1-13`
- `main/idf_component.yml:1-55`
- `makeimg.py:81-222`

## 数据与状态
- 构建期配置
  - 板型标志：MPY_PORT_DIR/MICROPY_BOARD/MICROPY_BOARD_DIR、MICROPY_BOARD_VARIANT。
  - 目标芯片：IDF_TARGET（esp32s3）。
  - SDK 配置：SDKCONFIG_DEFAULTS 合并多个 sdkconfig.* 文件，最终输出 sdkconfig.combined。
  - 冻结清单：MICROPY_FROZEN_MANIFEST 指向各板型 manifest.py。
- 运行时依赖
  - IDF 组件：app_update/bootloader_support/bt/driver/esp_wifi/nvs_flash/sdmmc/spi_flash/vfs 等。
  - 外设与协议栈：tinyusb（CDC）、lwip、mbedtls、nimble（BLE）、esp_lcd、esp32-camera、esp-sr 等。
- 存储与分区
  - 分区表由 partition-table.bin 描述，包含 bootloader、partitions、application、vfs(LittleFS)、voice_data、model(SR 模型) 等。
  - makeimg.py 按偏移写入各段，校验溢出并生成最终固件镜像；S3 平台额外生成 UF2。

```text
graph TB
subgraph "构建期"
A["mpconfigboard.cmake<br/>设置 IDF_TARGET/SDKCONFIG_DEFAULTS"] --> B["esp32_common.cmake<br/>注册组件/链接依赖"]
B --> C["idf_component.yml<br/>声明外部组件版本/路径"]
end
subgraph "运行期"
D["bootloader"] --> E["partition-table.bin"]
E --> F["application (micropython.bin)"]
E --> G["vfs (littlefs.bin)"]
E --> H["voice_data / model"]
end
C --> B
```

图表来源
- `boards/mpython_v3/mpconfigboard.cmake:5-13`
- `esp32_common.cmake:182-224`
- `main/idf_component.yml:1-55`
- `makeimg.py:144-186`

章节来源
- `boards/mpython_v3/mpconfigboard.cmake:5-13`
- `esp32_common.cmake:182-224`
- `main/idf_component.yml:1-55`
- `makeimg.py:144-186`

## 关键约束与边界
- 构建环境
  - 需要 ESP-IDF v5.2+（见 idf_component.yml），且存在 IDF_PATH 环境变量。
  - 构建前需确保 lockfiles 一致，否则维护者构建会失败或警告。
- 板型差异
  - mpython_v3 与 labplus_Ledong_v2 共享基础配置，后者额外引入 ESP-Who 组件目录以启用摄像头/AI 视觉能力。
  - 不同板型的 builtin 源与 frozen manifest 可能不同，需按 mpconfigboard.cmake 配置。
- 组件依赖
  - esp_lcd_jd9853 依赖 esp_lcd 与 driver；gen_bmgr_codes 依赖 esp_board_manager 并以 WHOLE_ARCHIVE 整包链接。
  - TinyUSB 针对 S3/S2/P4 启用，并通过补丁分支解决 DWC2 ZLP 问题。
- 存储与分区
  - 最终镜像大小受分区表限制，makeimg.py 会在写入时检测溢出并报错退出。
  - 若启用原生 USB 烧录，S3 平台会自动生成 UF2 以便拖拽烧录。

章节来源
- `main/idf_component.yml:51-55`
- `CMakeLists.txt:95-106`
- `boards/labplus_Ledong_v2/mpconfigboard.cmake:43-49`
- `components/esp_lcd_jd9853/CMakeLists.txt:1-8`
- `components/gen_bmgr_codes/CMakeLists.txt:1-13`
- `makeimg.py:190-222`